home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.033 < prev    next >
Encoding:
Text File  |  1989-01-04  |  4.4 KB  |  84 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Apple IIGS
  8. #33:    ERRORDEATH Macro
  9.  
  10. Revised by:    Jim Mensch & Matt Deatherage                     November 1988
  11. Written by:    Allan Bell, Apple Australia & Jim Merritt        December 1987
  12.  
  13. This Technical Note presents a short macro which an assembly language program 
  14. can invoke to handle fatal error conditions.
  15. _____________________________________________________________________________
  16.  
  17. Early versions of Apple-approved sample assembly language code for the Apple 
  18. IIGS often invoked an APW macro named ERRORDEATH.  This macro generated code 
  19. that was appropriate for handling situations where program execution simply 
  20. could not proceed due to "fatal" errors, such as a failure to load one or more 
  21. tools that are required to display more sophisticated error dialogs or the 
  22. inability to allocate sufficient direct page space for essential tool sets.  
  23. The macro libraries of prototype APW systems included ERRORDEATH, but the 
  24. release version does not to promote the use of more sophisticated error 
  25. handling techniques in commercial software packages.  The MPW IIGS release 
  26. never included ERRORDEATH.
  27.  
  28. Below are two versions of ERRORDEATH; one is compatible with official standard 
  29. releases of APW and the other with MPW IIGS.  While Apple recommends avoiding 
  30. the use of ERRORDEATH in software intended for commercial release, we feel the 
  31. code is still useful for providing minimal error handling capability in 
  32. prototype code and a brief, yet sophisticated, example of macro construction.
  33.  
  34. APW Assembler version:                    MPW IIGS Assembler version:
  35.         MACRO                                        MACRO
  36. &lab        ERRORDEATH &text                         ErrorDeath &text
  37. &lab        bcc end&syscnt                           bcc @EDeathEnd
  38.             pha                                      pha
  39.             pea x&syscnt|-16                         pea @Message>>16
  40.             pea x&syscnt                             pea @Message
  41.             ldx #$1503                               ldx #$1503
  42.             jsl $E10000                              jsl $E10000
  43. x&syscnt    dc i1'end&syscnt-x&syscnt-1'  @Message   dc.B @EDeathEnd-@Message-1
  44.             dc c"&text"                              dc.B  &text
  45.             dc i1'13',i1'13'                         dc.B  13
  46.             dc c'Error was $'                        dc.B  'Error Was $'
  47. end&syscnt  anop                          @EDeathEnd
  48.         MEND                                         MEnd
  49.  
  50. The "active ingredient" in the ERRORDEATH macro is the call to SysFailMgr 
  51. ($1503), which is made if carry is set at the time control passes to the 
  52. beginning of the expanded macro code sequence.  The APW and MPW IIGS assembler 
  53. macro expansion mechanisms insert the value represented by the character 
  54. string argument marker, &text, into the generated code stream and provide 
  55. SysFailMgr with a pointer to that string.  The pseudo-argument, &syscnt, 
  56. generates unique labels in the positions occupied by the expressions x&syscnt 
  57. and end&syscnt, which makes it possible to invoke ERRORDEATH more than once 
  58. during any particular source assembly.  In the MPW IIGS version of the macro, 
  59. the MPW IIGS assembler creates a unique label for any label beginning with the 
  60. at sign (@), effectively doing the equivalent of the &syscnt in the APW 
  61. version.
  62.  
  63. To use ERRORDEATH, simply invoke it after any code sequence or subroutine call 
  64. that sets the carry when it encounters an error (clears it, otherwise) and 
  65. leaves an appropriate error code in the accumulator.  Note that all ProDOS and 
  66. Toolbox calls observe this convention.  When control passes to the beginning 
  67. of the ERRORDEATH code sequence, the CPU should be in full-native mode, which 
  68. means the emulation bit should be clear and the accumulator and index 
  69. registers should be 16-bits wide).  Here is a small code segment which 
  70. demonstrates invoking the macro:
  71.  
  72.                 pushword #21            ; Dialog Manager
  73.                 pushword #0             ; Use any version
  74.                 _LoadOneTool
  75.     
  76.     ; If carry is now SET, following macro terminates program execution
  77.     ; with the "sliding Apple" error screen.
  78.     
  79.     IfWeGoofed    ERRORDEATH 'Cannot load Dialog Manager!'
  80.     
  81.     ; *** If no error, normal execution continues here ***
  82.  
  83.  
  84.